This file contains the information necessary to use Amnesia for simple tasks in a form suitable for the inexperienced programmer. It describes how to write a simple program in BASIC.
A Simple Amnesia Program
------------------------
Programs using Amnesia to display and move objects on the screens must do the following things:
(1) Initialise Amnesia
(2) Arrange a way to plot sprites
(3) Set up some sort of table of objects
(4) Create objects in that table
(5) Process the table
Iæll deal with each of these in turn.
(1) Initialising Amnesia
========================
When you initialise Amnesia you basically tell it which bit of memory you want it to use.
Instruction
SYS "Amnesia_Init",address,length,type
address= the address of the memory you want Amnesia to use
length = the amount of memory available to it there
type = the type of area. Type 2 is best suited for BASIC programs.
Example
At the start of your program you would code something like
arealen=&4000 ;16Kbytes
DIM area arealen ;Tell BASIC to reserve some memory for you
;of length arealen, and put the address of the
;memory itæs reserved in the variable 'area'
SYS "Amnesia_Init",area,arealen,2 ;Tell Amnesia
If you want to keep it really simple you can put the Amnesia area in the RMA. Simple pass zero as your area address. Only one line is needed
SYS "Amnesia_Init",0,&4000,2
This has the advantage that if you return to the Desktop, your Amnesia area will still be there so you can use the debugging command.
Notes
You can work out the right value of arealen by trial and error. If itæs too small, Amnesia will give you a 'Not enough memory' error, so you can increase arealen and try again.
(2) Arranging a Way to Plot Sprites
===================================
Amnesia is designed to work with the FastSpr module. You should have received a copy with Amnesia, with instructions and a sprite file maker. You donæt have to use FastSpr, but it will make things easier.
Firstly, make sure FastSpr is loaded:
*Run FastSpr:!Run
This will load the module. Itæs best placed in your !Run file (more of that later) but can be in your main program if you wish.
FastSpr loads files using the following command:
*FastSprLoad 1 FSPSprites
This will load a file called FSPSprites into sprite pool 1. You can load lots of sprite files - each into a different pool.
See the instructions with FastSpr for more information.
(3) Set Up Some Sort of Table of Objects
========================================
Tables of objects are Amnesiaæs bread and butter. They are a powerful way to handle the player, aliens, bombs, bullets and really anything that needs to be plotted as a sprite on the screen. Before you can use a table, you must tell Amnesia what sort of table you want.
Instruction
SYS "Amnesia_ClaimTable",table number,flags,name$,number of objects, length of objects
The table number is a number from 1-31, which you will use to identify the table later.
If flags=1 Amnesia will prepare this table for collision checking - otherwise not.
name$ is for your use only. It is used to make the debugging information more readable. The name may be up to 8 letters long. Names like "Aliens" or "Bullets" are good.
The number of objects is just that. If you want 20 aliens, set this number to 20. Note that this is the maximum number - if you specified 20, you could have any number up to 20, but no more.
The length of the objects is the number of bytes given to each object. Use 32 for standard objects.
Example
SYS "Amnesia_ClaimTable",1,1,"Aliens",27,32
This command sets up table 1 with 27 spaces for objects 32 bytes long, and tells Amnesia that we will need to collision check these objects.
(4) Create Objects In That Table
================================
So youæve created an empty table. You need to create some objects in that table, like bullets or aliens etc. There are various ways to do this, but the easiest is with the purpose built SWI.
Itæs a big one, isnæt it! Iæll go through each number in turn.
Table number : The same number you gave to Amnesia_ClaimTable as a table number.
Sprite number : See the information with FastSpr for full info, but briefly the number is in the form &xx00yyyy where x is the sprite pool, and y is the sprite number. &02000003 would mean sprite 3 from sprite pool 2.
Flags : This value tells Amnesia what sort of properties the object has. Whether it moves, whether it has a timer, whether it is animated, whether it obeys gravity etc etc. A full list of flags is in the flags help file. Hereæs a couple for the moment.
If bit 0 is set, the object is plotted by FastSpr
If bit 2 is set, the object moves
x coord : The x position of the sprite (remember, x is a cross 8-) ). Amnesia uses different coordinates to normal BASIC. The top-left of the screen is (0,0) and in MODE 13 (320x256) the bottom right is (320<<12,256<<12). 320<<12 means 320 shifted right 12 places in binary, which is the same as multiplying by 4096.
y coord : Similarly
x velocity : The velocity is added to the x coordinate every time the table is processed (see later in (5)) if and only if bit 2 is set in the flags.
y velocity : Similarly
timer : The timer can be thought of as split into two halves, like &xxxxyyyy. x is the timer value, and y is the value subtracted from the timer on each process pass (see (5)). So if the timer value is &012C0003, the timer value is &12C and 3 is subtracted on each process pass. With this value, the timer will expire after 100 process passes (&12C=300).
size : Again this is split like the timer. The value is of the form &xxxxyyyy, where x is the x size in pixels, and y is the y size. So for a sprite 32 pixels wide and 16 high, the value would be &00200010. You can ask Amnesia to work out the size from the FastSpr file by setting bit 6 in the flags. This is usually a good idea.
(5) Processing the Table
========================
Table processing is controlled by two SWIs - Amnesia_SelectTable and Amnesia_ProcessTable. These SWIs communicate using registers R0, R1 and R2. A typical table process goes like this:
SYS "Amnesia_SelectTable",1,0,0 TO R0,R1,R2
REPEAT
SYS "Amnesia_ProcessTable",R0,R1,R2 TO R0,R1,R2
UNTIL R2=0
Amnesia_SelectTable is called to tell Amnesia which table you wish to processand what you want to do with that table. Read its entry in the SWI docs for a full explanation. With the parameters above it selects table 1 for a standard process.
This table process will simply plot and move your objects. You can do a lot more than this when you process a table. See the help file called Process for more information.
